//+------------------------------------------------------------------+
//|                   DXSurface.mqh DirectX 3D 曲面渲染类头文件      |
//|                版权所有 2000-2025, MetaQuotes Ltd.              |
//|                        官方网址: https://www.mql5.com            |
//+------------------------------------------------------------------+
#property copyright "Copyright 2000-2025, MetaQuotes Ltd."  // 版权声明
#property link      "https://www.mql5.com"                 // 官方链接

#include "DXMesh.h"    // 引入 3D 网格基类（提供顶点/索引缓冲、渲染管线集成能力）
#include "DXMath.h"    // 引入 DirectX 数学工具类（向量、矩阵、颜色计算）
#include "DXUtils.h"   // 引入 DirectX 工具类（曲面顶点生成、颜色映射等辅助函数）

//+------------------------------------------------------------------+
//| CDXSurface 类                                                     |
//| 功能：MT5 DirectX 3D 曲面渲染类，基于网格基类实现数据驱动的曲面可视化 |
//| 继承关系：public CDXMesh（基于 3D 网格类，扩展曲面特有创建/更新逻辑）|
//| 核心特性：                                                      |
//|  1. 支持数据驱动曲面生成（通过二维数值数组生成高度场曲面）          |
//|  2. 提供曲面渲染控制标志（双面渲染、法向量启用，适配不同可视化场景）|
//|  3. 内置多种颜色映射方案（Jet、冷到热、红到绿，增强数据差异可视化）|
//|  4. 支持高效曲面更新（仅修改变化的顶点/索引数据，避免重复创建资源）|
//|  5. 继承网格基类的材质、纹理、变换控制能力（适配复杂渲染需求）      |
//+------------------------------------------------------------------+
class CDXSurface : public CDXMesh
  {
public:
   /**
    * @brief 曲面创建控制标志（位掩码，可组合使用）
    * @details 控制曲面生成时的渲染特性：
    *          - SF_NONE：默认值，单面渲染，不启用法向量
    *          - SF_TWO_SIDED：双面渲染（曲面正反面均可见，适用于透明/镂空曲面）
    *          - SF_USE_NORMALS：启用法向量计算（用于光照渲染，增强曲面立体感）
    */
   enum EN_SURFACE_FLAGS
     {
      SF_NONE        =0x0,       // 无特殊配置（单面渲染，无法向量）
      SF_TWO_SIDED   =0x1,       // 启用双面渲染
      SF_USE_NORMALS =0x2        // 启用法向量计算
     };

   /**
    * @brief 曲面颜色映射方案（根据数据值自动映射颜色，增强数据可视化效果）
    * @details 不同方案对应不同的颜色渐变逻辑，适用于不同数据特征的展示：
    *          - CS_NONE：默认白色（不启用颜色映射，所有顶点统一白色）
    *          - CS_JET：Jet 配色方案（蓝→青→黄→红，常用于科学数据可视化）
    *          - CS_COLD_TO_HOT：冷到热配色（蓝→绿→黄→红，体现数值从低到高的变化）
    *          - CS_RED_TO_GREEN：红到绿配色（红→黄→绿，体现数值从高到低的变化）
    */
   enum EN_COLOR_SCHEME
     {
      CS_NONE        =0,         // 无颜色映射（统一白色）
      CS_JET         =1,         // Jet 配色方案
      CS_COLD_TO_HOT =2,         // 冷色调到暖色调（低→高：蓝→红）
      CS_RED_TO_GREEN=3          // 红色到绿色（高→低：红→绿）
     };

protected:
   uint              m_data_width;    // 曲面数据宽度（二维数据数组的列数，对应曲面的 X 方向分段数）
   uint              m_data_height;   // 曲面数据高度（二维数据数组的行数，对应曲面的 Z 方向分段数）
   uint              m_flags;         // 曲面创建标志（EN_SURFACE_FLAGS 组合值，控制渲染特性）
   EN_COLOR_SCHEME   m_color_scheme;  // 颜色映射方案（EN_COLOR_SCHEME，控制顶点颜色生成逻辑）

public:
   /**
    * @brief 构造函数：初始化 3D 曲面渲染对象
    * @details 调用父类 CDXMesh 构造函数，初始化曲面数据尺寸、控制标志、颜色方案等参数为默认值
    */
                     CDXSurface();

   /**
    * @brief 析构函数：销毁 3D 曲面渲染对象
    * @details 依赖父类 CDXMesh 的析构逻辑，自动释放曲面关联的顶点/索引缓冲、着色器等资源
    */
                    ~CDXSurface();

   //--- 曲面创建接口（基于二维数据生成高度场曲面）
   /**
    * @brief 创建 3D 曲面（从二维数值数据生成高度场，数据驱动曲面形态）
    * @param dispatcher [in] DirectX 资源调度器（用于创建曲面依赖的顶点/索引缓冲、着色器等资源）
    * @param buffer_scene [in] 场景级常量缓冲（传递视图、投影、光照参数，不可为 NULL）
    * @param data [in] 二维曲面数据数组（double 类型，按 [行][列] 存储，值对应曲面在该点的高度）
    * @param data_width [in] 数据宽度（数组列数，≥2，对应曲面 X 方向的分段数量）
    * @param data_height [in] 数据高度（数组行数，≥2，对应曲面 Z 方向的分段数量）
    * @param data_range [in] 数据值缩放范围（将原始数据值映射到该范围内，控制曲面高度差）
    * @param from [in] 曲面左下角起始坐标（3D 空间位置，X/Z 对应数据范围，Y 对应高度基准）
    * @param to [in] 曲面右上角结束坐标（3D 空间位置，与 from 共同定义曲面在 X/Z 方向的大小）
    * @param texture_size [in] 纹理缩放比例（2D 向量，控制纹理在曲面上的重复次数，如 (2,2) 表示纹理重复 2 次）
    * @param flags [in] 曲面创建标志（EN_SURFACE_FLAGS 组合值，默认 SF_NONE）
    * @param color_scheme [in] 颜色映射方案（EN_COLOR_SCHEME，默认 CS_NONE）
    * @return bool - 操作结果：true 表示创建成功（顶点/索引生成+资源初始化完成），false 表示失败（数据无效/资源创建失败）
    * @note 创建前会自动释放旧资源；曲面由三角形网格组成，每个数据点对应一个顶点，相邻顶点组成三角形
    */
   bool              Create(CDXDispatcher &dispatcher,CDXInput* buffer_scene,
                            double &data[],uint data_width,uint data_height,float data_range,
                            const DXVector3 &from,const DXVector3 &to,DXVector2 &texture_size,
                            uint flags=SF_NONE,EN_COLOR_SCHEME color_scheme=CS_NONE);

   //--- 曲面更新接口（高效修改曲面数据/形态，避免重复创建资源）
   /**
    * @brief 更新 3D 曲面（修改数据、位置、颜色方案等，仅更新变化的资源）
    * @param data [in] 新的二维曲面数据数组（若与原数据尺寸一致，仅更新顶点高度；尺寸变化则需重新生成索引）
    * @param data_width [in] 新的数据宽度（若与原 m_data_width 不一致，需重新生成索引）
    * @param data_height [in] 新的数据高度（若与原 m_data_height 不一致，需重新生成索引）
    * @param data_range [in] 新的数据值缩放范围（控制更新后曲面的高度差）
    * @param from [in] 新的曲面起始坐标（修改曲面在 3D 空间的位置和 X/Z 方向大小）
    * @param to [in] 新的曲面结束坐标（与 from 共同定义曲面新的空间范围）
    * @param texture_size [in] 新的纹理缩放比例（修改纹理在曲面上的重复效果）
    * @param flags [in] 新的曲面创建标志（若与原 m_flags 的 SF_TWO_SIDED 不一致，需重新生成索引）
    * @param color_scheme [in] 新的颜色映射方案（修改顶点颜色，无需重新生成顶点/索引）
    * @return bool - 操作结果：true 表示更新成功（仅修改变化的顶点/索引数据），false 表示失败（数据无效/资源更新失败）
    * @note 高效更新逻辑：仅当数据尺寸或双面渲染标志变化时才更新索引，其他情况仅更新顶点数据（高度、颜色、纹理坐标）
    */
   bool              Update(double &data[],uint data_width,uint data_height,float data_range,
                            const DXVector3 &from,const DXVector3 &to,DXVector2 &texture_size,
                            uint flags=0,EN_COLOR_SCHEME color_scheme=CS_NONE);

private:
   /**
    * @brief 生成曲面顶点颜色（内部辅助方法，根据颜色方案映射数据值到顶点颜色）
    * @param vertices [in/out] 顶点数据数组（需已生成位置、法向量等信息，此方法仅更新 vcolor 字段）
    * @param from [in] 曲面起始坐标（用于计算顶点高度相对值，映射到 [0,1] 范围以匹配颜色方案）
    * @param to [in] 曲面结束坐标（与 from 共同计算高度范围，确保颜色映射的一致性）
    * @note 逻辑：根据顶点 Y 坐标（高度）计算相对值（[0,1]），再通过对应颜色方案（如 Jet）生成 RGBA 颜色
    */
   void              PrepareColors(DXVertex &vertices[],const DXVector3 &from,const DXVector3 &to);
  };
//+------------------------------------------------------------------+